ejson-kms (AWS)

2022-08-22 ยท 2 min read

    A utility for managing a collection of secrets in source control using AWS KMS.

    The secrets are encrypted using secret-key cryptography (NaCl Secretbox: XSalsa20 + Poly1305), using key wrapping with a master key stored on HSM-backed storage at AWS. Encrypted secrets are stored in a JSON file that can easily be shared and versioned.

    secret encryption #

    • For each secret, a data key is requested from AWS KMS (see GenerateDataKey).
    • The encryption context is sent along and is stored alongside the encrypted data key. The name of the secret is added to the context automatically under the key Secret
    • KMS returns the data key encrypted with the master key (stored on AWS servers) and the corresponding plaintext.
    • That data key is used to encrypt one secret.
    • A random nonce is generated and NaCL Secretbox is used for encryption.
    • Under the hood, Secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages. The length of messages is not hidden.
    • Finally, the encrypted data key, the random nonce and the encrypted secret are each stored in the JSON file.

    secret decryption #

    • For each secret, the encrypted data key, random nonce and encrypted secret are extracted from the JSON file.
    • A request is made to AWS KMS to decrypt the encrypted data key (see Decrypt).
    • At this stage the encryption context is authenticated and logged. The name of the secret is added to the context automatically under the key Secret
    • Using the key plaintext and random nonce, the secret is decrypted using NaCL Secretbox.